---
id: tree-view
title: Tree View
status: preview
description: A component that is used to show a tree hierarchy.
---

<ComponentPreview id="TreeView" />

## Anatomy

To set up the tree view component correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="tree-view" />

## Examples

Learn how to use the `TreeView` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Controlled Expanded

Pass the `expandedValue` and `onExpandedChange` props to the `TreeView.Root` component to control the expanded state of
the tree view.

<Example id="controlled-expanded" />

### Controlled Selection

Pass the `selectedValue` and `onSelectionChange` props to the `TreeView.Root` component to control the selected state of
the tree view.

<Example id="controlled-selected" />

### Root Provider

Use the `useTreeView` hook to create the tree view store and pass it to the `TreeView.RootProvider` component. This
allows you to have maximum control over the tree view programmatically.

<Example id="root-provider" />

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

### Lazy Loading

Lazy loading is a feature that allows the tree view to load children of a node on demand (or async). This helps to
improve the initial load time and memory usage.

To use this, you need to provide the following:

- `loadChildren` — A function that is used to load the children of a node.
- `onLoadChildrenComplete` — A callback that is called when the children of a node are loaded. Used to update the tree
  collection.
- `childrenCount` — A number that indicates the number of children of a branch node.

<Example id="async-loading" />

### Lazy Mount

Lazy mounting is a feature that allows the content of a tree view to be rendered only when it is expanded. This is
useful for performance optimization, especially when tree content is large or complex. To enable lazy mounting, use the
`lazyMount` prop on the `TreeView.Root` component.

In addition, the `unmountOnExit` prop can be used in conjunction with `lazyMount` to unmount the tree view content when
branches are collapsed, freeing up resources. The next time a branch is expanded, its content will be re-rendered.

<Example id="lazy-mount" />

### Filtering

Filtering is useful when you have a large tree and you want to filter the nodes to only show the ones that match the
search query. Here's an example that composes the `filter` method from the `TreeCollection` and `useFilter` hook to
filter the nodes.

<Example id="filtering" />

### Links

Tree items can be rendered as links to another page or website. This could be useful for documentation sites.

Here's an example that modifies the tree collection to represent an hierarchical link structure. It uses the `asChild`
prop to render the tree items as links, passing the `href` prop to a `<a>` element.

<Example id="links" />

## Guides

### Type-Safety

The `TreeView.RootComponent` type enables you to create closed, strongly typed wrapper components that maintain full
type safety for tree nodes.

This is particularly useful when building reusable tree view components with custom props and consistent styling.

```tsx
import { TreeView as ArkTreeView, type TreeNode } from '@ark-ui/react/tree-view'
import { createTreeCollection } from '@ark-ui/react/collection'

interface TreeViewProps<T extends TreeNode> extends ArkTreeView.RootProps<T> {}

const TreeView: ArkTreeView.RootComponent = (props) => {
  return <ArkTreeView.Root {...props}>{/* ... */}</ArkTreeView.Root>
}
```

Then, you can use the `TreeView` component as follows:

```tsx
const App = () => {
  const collection = createTreeCollection({
    initialItems: [
      { id: '1', label: 'React', children: [] },
      { id: '2', label: 'Vue', children: [] },
      { id: '3', label: 'Svelte', children: [] },
    ],
  })
  return (
    <TreeView
      collection={collection}
      onSelectionChange={(e) => {
        // this will be strongly typed Array<{ id: string, label: string, children: [] }>
        console.log(e.value)
      }}
    >
      {/* ... */}
    </TreeView>
  )
}
```

## API Reference

### Props

<ComponentTypes id="tree-view" />

### Context

These are the properties available when using `UtreeUview.Context`, `useUtreeUviewContext` hook or `useUtreeUview` hook.

<ContextType id="tree-view" />

## Accessibility

Complies with the [Tree View WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).

### Keyboard Support

<KeyBindingsTable id="tree-view" />
